BSAVED Image Format Specifications Apple II
by Bill Buckels 2007

http://en.wikipedia.org/wiki/BSAVE_(graphics_image_format)#Specifications_Apple_II

Copyright (c) 2008 Bill Buckels 

Permission is granted to copy, distribute and/or modify this document 
under the terms of the GNU Free Documentation License, Version 1.2 
or any later version published by the Free Software Foundation; 
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 

Graphics

The Apple II had 2 graphics modes; HGR and HGR2. HGR was a "mixed text
and graphics" mode and only offered a partial display of a graphics
image. HGR2 was most commonly used since it was a "pure" graphics mode.
HGR2 ("page 2") started at memory address 4000 hex ($4000).

Resolution

The resolution of an Apple II Graphics screen was 280 pixels x 192
rasters and allowed up to 6 colors to be displayed simultaneously.
However, the hardware was designed to interpret the colors based on
"rules" of pixel arrangement in a raster line, and colors would "bleed"
(artifact) into each other if the pixels were incompatibly arranged. This
was a memory saving technique that allowed a 6 color image to be
displayed in only 8K of video memory.

File Format

The size of an Apple II BSAVE image was 8K (the same size as the video
memory) plus 4 byte header, and was interleaved in sections, and was not
"linearized". Like all BIN (Binary) files on the Apple II, the file had a
binary header of 4 bytes (2 integers) in addition to the 8K binary
(image) data following the header.

The first integer gave the load address for the file, and the second gave
the length in bytes.

The file extension was usually .BIN or .PIC, if a file extension was used
at all.

Rasters (scanlines)

The rasters in an Apple II BSAVED image are not contiguous, nor are they
in a simple sequential order. They match the video memory on the Apple II
which was relatively complicated, and are arranged as follows:

Each scanline is 40 bytes long. There are 3 parent interleaves of 64
scanlines each. Starting at the beginning of the image file, scanlines
are arranged in 128 byte blocks beginning with scanlines 0, 64, and 128
in the first block (see table below). 8 bytes at the end of each block
are unused by the image.

Each parent interleaf has 8 child interleaves of 8 scanlines each, with a
spacing of 1024 bytes (1K) between sequential scanlines in each of the 3
parent interleaves.

Starting at the beginning of the file and respective of the Apple II's
interleaved display, the first 8 of the 128 byte blocks run as shown
below. This also represents the first of 8 scanlines in each of the 24
child interleaves, and is effectively a block group. 8 of these block
groups are stored in the file, with the scanlines in the table below
being incremented by 1 for each subsequent block group sequence of 1024
bytes, totalling 8192 bytes (8K) of graphics image data.

First of 8 Sequential Scanline Block Groups in Apple II BSAVE Image
1024 Bytes (1K) 
 Block Leaf 1 - Offset 0
40 Bytes Leaf 2 - Offset 40
40 Bytes Leaf 3 - Offset 80
40 Bytes Padding - Offset 120
8 Bytes 
Scanlines 1 0 64 128 Unused 
Scanlines 2 8 72 136 Unused 
Scanlines 3 16 80 144 Unused 
Scanlines 4 24 88 152 Unused 
Scanlines 5 32 96 160 Unused 
Scanlines 6 40 104 168 Unused 
Scanlines 7 48 112 176 Unused 
Scanlines 8 56 120 184 Unused 

Because of the interleaved display and the slow processor speed of the
Apple II, when these loaded, a visible "venetian blind" effect was
produced creating a "wipe" (fade effect) of the previous graphic if any.

Pixels (colors)

The colors in an Apple II BSAVED image are Black, Green, Violet, Orange,
Blue, and White. Pixel color is represented by 2 bits. Although the
nominal resolution is 280 x 192, the effective resolution considering
colors is really only 140 x 192.

In a 40 byte scanline pixels are stored in an bit array of 280 pixel
positions referred to as "columns". The highest bit of each byte is used
as a "palette" bit and is not considered a column. The lowest bit
represents the first column in the byte. So a scan line beginning with
$03 would have the first two pixel positions set as white (with the next
5 pixels black).

If the palette bit in a byte is set, the 4 colors available for the
pixels in that byte are black, blue, orange, and white.

If the palette bit is not set, the 4 colors available for the pixels in
that byte are black, violet, green, and white

Ignoring the 40 palette bits in in a 40 byte scanline, there are 280
columns (bits, pixel positions) but only 140 available pixels. So
considering each pixel as being a column pair, with an even and odd
column, from left to right starting at column 0, if even is set and odd
is not set, the pixel is blue or violet. If even is not set and odd is
set, the pixel is orange or green. Any two adjacent columns that are set
will be white. This means that white pixels (and black pixels) can be
positioned at more places than the other colors, but does not alter the
fact that the effective resolution is really only 140 x 192 for an Apple
II BSAVED image.

BLOAD Example

To BLOAD a previously BSAVED image, use the Apple DOS/ProDOS command:

BLOAD <filename>

The following AppleSoft BASIC program loads a BSAVED Apple II Graphics
Screen under Apple DOS 3.3. First it clears the screen, lists a
directory, waits for user input (the BSAVED screen name) and then loads
the screen and waits for a keypress, and repeats until the user ends the
program.

1 REM This source code is herewith released 
2 REM by me into the Public Domain.
3 REM Bill Buckels, May 31, 2007
10 TEXT
20 HOME
30 CALL - 1184: CALL 42350
40 PRINT "---------------------------------"
50 PRINT "ABINLOAD(C) APPLEII SCREEN LOADER" 
60 PRINT "COPYLEFT BILL BUCKELS 2006"
70 PRINT "ENTER BIN FILE OR BLANK TO END..."
80 PRINT "---------------------------------"
90 INPUT "?"
100 IF BIN$ = "" THEN GOTO 500
110 HGR2
120 PRINT CHR$(4)"BLOAD "BIN$",A$4000"
130 GET A$
140 GOTO 10
500 TEXT
510 CALL - 1184: CALL 42350
520 END

BSAVE Example

To BSAVE the HGR screen (starting at memory location $2000, for a length
of $2000) use the Apple DOS/ProDOS command:

BSAVE <filename>,A$2000,L$2000 To BSAVE the HGR2 screen (starting at
memory location $4000, for a length of $2000) use the Apple DOS/ProDOS
command:

BSAVE <filename>,A$4000,L$2000
